Mac OS Documentation For Windows Developers

Although QuickTime 3 is truly cross-platform --you use one API for compilation to either Windows or the Mac OS-- developers for the Windows platform need to understand some facets of Mac OS programming.

If you are a Windows developer and are not familiar with the Mac OS, first read QuickTime 3 for Windows Programmers .

This chapter lists the main Mac OS routines and data structures that developers of QuickTime 3 applications may need to use. These chapters of Inside Macintosh are provided in HTML and PDF formats.

Table 1 Mac OS documentation of interest to Windows developers
Symbol	Books and chapters
InMacF	Inside Macintosh: Files Chapter 1, "Introduction to File Management" Chapter 3, "Standard File Package"
InMacIm	Inside Macintosh: Imaging with QuickDraw Chapter 4, "Color QuickDraw" Chapter 5, "Graphics Devices" Chapter 6, "Offscreen Graphics Worlds" Chapter 7, "Pictures"
InMacM	Inside Macintosh: Memory Chapter 1, "Introduction to Memory Management" Chapter 2, "Memory Manager"
InMacTb	Inside Macintosh: Macintosh Toolbox Essentials Chapter 2, "Event Manager" Chapter 4, "Window Manager"

Memory Management

Inside Macintosh: Memory describes routines in Mac OS that help you create and dispose of pointers and handles. Introduction to Memory Management describes memory management within an application's memory partition; Memory Manager describes memory management outside the partition. The following functions are described in both chapters:

NewHandle allocates a relocatable memory block of a specified size. To use it outside an application's memory partition, see Memory Manager .
NewHandleClear allocates prezeroed memory in a relocatable block of a specified size. To use it outside an application's memory partition, see Memory Manager .
DisposeHandle frees a relocatable block and its master pointer for other uses. To use it outside an application's memory partition, see Memory Manager .
NewPtr allocates a nonrelocatable block of memory of a specified size. To use it outside an application's memory partition, see Memory Manager .
NewPtrClear allocates prezeroed memory in a nonrelocatable block of a specified size. To use it outside an application's memory partition, see Memory Manager .
DisposePtr frees a nonrelocatable block for other uses. To use it outside an application's memory partition, see Memory Manager .

Mac OS File System

Introduction to File Management documents several Mac OS API elements of interest to QuickTime 3 developers. Standard File Package describes how an application can use the Mac OS standard file package to manage the user interface for naming and identifying files.

You can use the following functions and data structures to retrieve user-selected files from the Mac OS file system:

The File System Specification Record FSSpec provides a simple, standard format for specifying Mac OS files and directories.
FSMakeFSSpec initializes a file system specification record to particular values for a file or directory.
Standard File Reply Records identify files and folders with a file system specification record. For additional features and information, see Standard File Package .
StandardGetFile displays the Mac OS default Open dialog box and returns a StandardFileReply data structure. For further information, see Standard File Package .
StandardPutFile displays the default Save dialog box when the user is saving a file. For further information, see Standard File Package .

QuickDraw

Macintosh QuickDraw is a collection of system-level functions and data structures that other software can use to perform most operations that manipulate static two-dimensional images. Information about QuickDraw of interest to QuickTime 3 developers is contained in Chapters 4, 5, 6, and 7 of Inside Macintosh: Imaging with QuickDraw, as described below.

Drawing Environment

Chapter 4, " Color QuickDraw ," contains a section, " The Color Drawing Environment: Color Graphics Ports ," that describes CGrafPort . This data structure defines a complete drawing environment that determines where and how graphics operations take place.

Graphics Devices

Chapter 5, " Graphics Devices ," contains a section " Creating, Setting, and Disposing of GDevice Records ." This section tells you how to use Graphic Device records (of type GDevice ), which store state information for video devices and offscreen graphics worlds.

QuickDraw Operations

When using QuickDraw with QuickTime, you may want to work offscreen. Chapter 6, " Offscreen Graphics Worlds ," describes the following functions and data structures that QuickTime 3 programmers can access:

NewGWorld creates an offscreen graphics world. It uses NewScreenBuffer and NewTempScreenBuffer to create an offscreen PixMap record and allocate memory for the base address of its pixel image. It returns a pointer of type GWorldPtr by which your application refers to the offscreen graphics world. These types are described in " Data Structures ".
UpdateGWorld changes the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world.
DisposeGWorld uses DisposeScreenBuffer to dispose of all the memory allocated for an offscreen graphics world.
GetGWorld gets the current graphics port (color graphics port or offscreen graphics world) and the current GDevice record (see " Creating, Setting, and Disposing of GDevice Records ").
SetGWorld changes the current graphics port (color graphics port or offscreen graphics world).
GetGWorldDevice obtains a handle to the Graphic Device record associated with an offscreen graphics world.
GetGWorldPixMap obtains the pixel map previously created for an offscreen graphics world.
LockPixels prevents the base address of an offscreen pixel image from being moved while you draw into or copy from its pixel map.
UnlockPixels frees the base address of an offscreen pixel image when you have finished drawing into or copying from an offscreen graphics world.
GetPixelsState saves current information about the memory allocated for an offscreen pixel image.
SetPixelsState restores an offscreen pixel image to the state previously saved by GetPixelsState .
GetPixBaseAddr obtains a pointer to an offscreen pixel map.

Several of the routines listed above expect or return values defined by the GWorldFlags data type, which specify a number of options for offscreen graphics worlds. It is described in " Data Structures ".

Pictures

Mac OS pictures are stored in Picture Records , data structures of type Picture . Chapter 7, " Pictures ," describes this data type and the DrawPicture routine, which draws a picture stored in a Picture Record on any type of output device.

Window Management

Mac OS window management is discussed in " Window Manager Reference ," in Chapter 4 of Inside Macintosh: Macintosh Toolbox Essentials . The SizeWindow function and the data structures listed below are of interest to Windows developers working with QuickTime 3:

The CWindowRecord data type defines the color window record for a window.
The CWindowPeek data type is a pointer to a window record. The first field in the window record is the record that describes the window's graphics port. For details, see " The Color Window Record ."
The CWindowPtr data type is defined as a CGrafPtr , which is a pointer to a graphics port (in this case, the window's graphics port). For details, see " The Color Window Record ."
SizeWindow sets the size of a Mac OS window.

Mac OS Events

Mac OS event management is discussed in " Event Manager Reference " in Chapter 2 of Inside Macintosh: Macintosh Toolbox Essentials . The Mac OS Event Manager returns information about retrieved events in an event record , a structure of type EventRecord .